feat(iOS, ContainedModal): Add basic setup for ContainedModal native component by sgaczol · Pull Request #4190 · software-mansion/react-native-screens

sgaczol · 2026-06-18T11:39:57Z

Things to do

add a prop regarding animation
add an event emitter and events handling
add a test regarding nesting providers

Description

Introducing the iOS implementation of the standalone ContainedModal component, together with its ContainedModalProvider.

A ContainedModal is presented within the bounds of a provider instead of over the whole window. The two are matched by id: the modal's targetContainerId is compared against a provider's containerId, and the modal is presented inside the matching provider's frame. This makes it possible to scope a modal to an arbitrary region of the screen (e.g. one column of a split layout) rather than the full screen.

Key architectural decisions:

On the JS side, the ContainedModal host is a zero-sized, absolutely-positioned logical anchor — it never participates in layout of its siblings. The actual React children are "teleported" and mounted inside a separate UIViewController hierarchy (RNSContainedModalContentController / RNSContainedModalContentView), so the host's hitTest: always returns nil and never intercepts touches meant for the content behind it.
The ContainedModalProvider is, by contrast, a regular space-filling container. Its bounds define the presentation area, and it hosts the UIViewController the modal is presented from (resolved once, lazily, by walking up to the provider whose containerId matches).
Presentation is state-driven: flipping isOpen from false → true presents the modal, and true → false dismisses it. The present/dismiss lifecycle and its state machine live in RNSContainedModalPresentationManager, kept separate from the controller and the component view.
Presentation style is selected from JS via the transparent prop: true (the default) uses UIModalPresentationOverCurrentContext, so the provider's content stays visible behind the presented modal, while false uses UIModalPresentationCurrentContext, replacing it. The transition style will eventually be exposed as a prop too, but for now it is hardcoded to UIModalTransitionStyleCrossDissolve.

This mirrors the architecture established for the standalone FormSheet component (#3947), reusing the same host-anchor + teleported-content + presentation-manager split.

Note

ContainedModal is currently an iOS-only component. The Android and Web entry points are present but no-ops for now. It is exported from react-native-screens/experimental.

Closes https://github.com/software-mansion/react-native-screens-labs/issues/1359
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1361
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1364
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1367
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1356
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1362
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1369

Changes

JS API & exports
- Added ContainedModal (isOpen, targetContainerId) and ContainedModalProvider (containerId, style) components, types, and platform splits (.tsx, .android.tsx, .web.tsx).
- Exposed both components via src/experimental.
Codegen
- Added Fabric native-component specs: ContainedModalHostNativeComponent and ContainedModalProviderNativeComponent.
C++ / shared layer
- Added the host shadow node, state, and component descriptor (RNSContainedModalHostShadowNode, RNSContainedModalHostState, RNSContainedModalHostComponentDescriptor).
iOS native implementation (ios/gamma/modals/contained-modal/)
- Host & provider component views, content view & content controller, providers protocol.
- Presentation manager (present/dismiss state machine), update coordinator & flags, configuration applicator, shadow-state proxy.
- Wired the gamma stubs (RNSGammaStubs).
Touch handling
- The content view's RCTSurfaceTouchHandler is attached lazily on present/layout and detached on viewDidDisappear: (via the controller→host delegate), in addition to invalidate. This prevents a dismissed modal from leaving behind a dead touch zone that silently swallows taps on the content behind it, and it re-attaches correctly on re-present.
Build
- Minor package.json wiring for the new sources.

Caution

Dynamic content-origin updates aren't supported in the context of synchronization with the ShadowTree state. If an ancestor's offset changes, the frame of our host view might not be updated at all — from the host's perspective the frame doesn't change (syncShadowNodeState only schedules a new state update when the computed origin or content bounds actually change), so no content re-layout is triggered.

Note

The JavaScript files unrelated to the single-feature test (a separate batch of .js/.ts changes) are tracked in their own PR — see #4171.

After - visual documentation

ContainedModalDemo.mov

Test plan

Run single feature tests regarding ContainedModal and verify if the modal's behaviors matches the expected ones in scenario.md files.

Checklist

Included code example that can be used to test this change (single-feature test).
For visual changes, included screenshots / GIFs / recordings documenting the change.
For API changes, updated relevant public types.
Ensured that CI passes.

Copilot

Pull request overview

Adds a new experimental iOS-contained modal primitive (ContainedModal) and its bounding container (ContainedModalProvider) to react-native-screens, including the Fabric/codegen surface, native iOS implementation (host anchor + teleported content + presentation manager), and a single-feature test scenario in the example app.

Changes:

Added JS components/types (with Android/Web no-op shims) and exported them via react-native-screens/experimental.
Added Fabric codegen specs + component registry wiring for the new host/provider native components.
Implemented the iOS native contained-modal stack (provider controller, host/proxy/state syncing, presentation manager/update coordination) and added a single-feature test scenario.

Reviewed changes

Copilot reviewed 45 out of 45 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/fabric/gamma/modals/contained-modal/ContainedModalProviderNativeComponent.ts	Codegen spec for the provider native component (Fabric).
src/fabric/gamma/modals/contained-modal/ContainedModalHostNativeComponent.ts	Codegen spec for the host native component (Fabric, interfaceOnly).
src/experimental/index.ts	Exports ContainedModal/Provider from the experimental entry point.
src/components/gamma/modals/contained-modal/index.ts	Barrel exports for the contained-modal components/types.
src/components/gamma/modals/contained-modal/ContainedModalProvider.web.tsx	Web no-op stub with warning.
src/components/gamma/modals/contained-modal/ContainedModalProvider.types.ts	Public JS types for `ContainedModalProvider`.
src/components/gamma/modals/contained-modal/ContainedModalProvider.tsx	iOS/native implementation wrapper using the provider native component.
src/components/gamma/modals/contained-modal/ContainedModalProvider.android.tsx	Android no-op stub with warning.
src/components/gamma/modals/contained-modal/ContainedModal.web.tsx	Web no-op stub with warning.
src/components/gamma/modals/contained-modal/ContainedModal.types.ts	Public JS types for `ContainedModal`.
src/components/gamma/modals/contained-modal/ContainedModal.tsx	iOS/native implementation wrapper using a zero-sized host anchor.
src/components/gamma/modals/contained-modal/ContainedModal.android.tsx	Android no-op stub with warning.
package.json	Registers the new Fabric component classes in the codegen component map.
ios/stubs/RNSGammaStubs.mm	Adds Gamma stubs for the new component views.
ios/stubs/RNSGammaStubs.h	Adds Gamma stub declarations for the new component views.
ios/gamma/modals/contained-modal/RNSContainedModalUpdateFlags.h	Defines update flags for presentation/appearance/behavior.
ios/gamma/modals/contained-modal/RNSContainedModalUpdateCoordinator.mm	Implements update-flag coordination helpers.
ios/gamma/modals/contained-modal/RNSContainedModalUpdateCoordinator.h	Declares update-flag coordination helpers.
ios/gamma/modals/contained-modal/RNSContainedModalProviders.h	Declares provider protocol used to drive presentation.
ios/gamma/modals/contained-modal/RNSContainedModalProviderController.mm	Defines a provider VC that sets `definesPresentationContext`.
ios/gamma/modals/contained-modal/RNSContainedModalProviderController.h	Header for provider VC.
ios/gamma/modals/contained-modal/RNSContainedModalProviderComponentView.mm	Provider Fabric component view embedding the provider VC and reparenting children.
ios/gamma/modals/contained-modal/RNSContainedModalProviderComponentView.h	Header for provider component view + containerId API.
ios/gamma/modals/contained-modal/RNSContainedModalPresentationState.h	Presentation state enum for manager state machine.
ios/gamma/modals/contained-modal/RNSContainedModalPresentationManager.mm	Present/dismiss state machine + provider resolution/caching.
ios/gamma/modals/contained-modal/RNSContainedModalPresentationManager.h	Header for presentation manager.
ios/gamma/modals/contained-modal/RNSContainedModalHostShadowStateProxy.mm	Updates Fabric shadow state with teleported content bounds/origin offset.
ios/gamma/modals/contained-modal/RNSContainedModalHostShadowStateProxy.h	Header for host shadow-state proxy.
ios/gamma/modals/contained-modal/RNSContainedModalHostComponentView.mm	Host anchor Fabric component view: mounts children into content VC, manages touch handler + state sync.
ios/gamma/modals/contained-modal/RNSContainedModalHostComponentView.h	Header for host component view.
ios/gamma/modals/contained-modal/RNSContainedModalContentView.mm	Clear background content view used by the presented controller.
ios/gamma/modals/contained-modal/RNSContainedModalContentView.h	Header for content view reparenting helpers.
ios/gamma/modals/contained-modal/RNSContainedModalContentController.mm	Presented controller: update flushing + presentation manager invocation + delegate callbacks.
ios/gamma/modals/contained-modal/RNSContainedModalContentController.h	Header for content controller and its signals/delegate.
ios/gamma/modals/contained-modal/RNSContainedModalConfigurationApplicator.mm	Placeholder configuration applicator (scaffolding).
ios/gamma/modals/contained-modal/RNSContainedModalConfigurationApplicator.h	Header for configuration applicator (scaffolding).
common/cpp/react/renderer/components/rnscreens/RNSContainedModalHostState.h	C++ state definition for host (frame size + content offset).
common/cpp/react/renderer/components/rnscreens/RNSContainedModalHostShadowNode.h	Shadow node definition with overridden content-origin offset.
common/cpp/react/renderer/components/rnscreens/RNSContainedModalHostShadowNode.cpp	Shadow node implementation.
common/cpp/react/renderer/components/rnscreens/RNSContainedModalHostComponentDescriptor.h	Component descriptor adopting size from state (layout integration).
apps/src/tests/single-feature-tests/index.tsx	Adds ContainedModal scenario group to example app scenario registry.
apps/src/tests/single-feature-tests/contained-modal/test-contained-modal-base-ios/scenario.md	Manual test plan/scenario for contained modal behavior.
apps/src/tests/single-feature-tests/contained-modal/test-contained-modal-base-ios/scenario-description.ts	Scenario metadata shown in the test app.
apps/src/tests/single-feature-tests/contained-modal/test-contained-modal-base-ios/index.tsx	Single-feature test implementation showcasing provider-bounded presentation + touch routing.
apps/src/tests/single-feature-tests/contained-modal/index.ts	Scenario-group entry point for contained-modal tests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sgaczol · 2026-06-18T12:50:20Z

+
+const ContainedModalScenarioGroup: ScenarioGroup<keyof typeof scenarios> = {
+  name: 'ContainedModal',
+  details: 'Single feature tests for ContainedModals',


'ContainedModals' makes more sense, especially when we add a different style (CurrentContext) in the future

LKuchno

Looks good, but I left few comments how we can optimize this to make manual testing a bit more convenient.

LKuchno · 2026-06-22T09:05:58Z

+
+1. Launch the app and navigate to the **Basic functionality** screen.
+
+- [ ] Expected: Content is shown with the "Provider: full screen (tap for partial)" button, an "Open contained modal" button, an "Outside count: 0" button, and (inside the provider region) an "Inside count: 0" button.


I would set a background color for the ContainedModalProvider (e.g., backgroundColor: Colors.NavyLightTransparent) to make the provider region visible. Right now, "(inside the provider region)" isn't visually testable.

Okay: aa4a870

Information about color should be provided also in scenario imo.

LKuchno · 2026-06-22T09:10:25Z

+6. Note the current "Inside count" value, then tap the "Inside count" button (the one
+   that sits in the region the modal was just covering) several times. Tap "Outside


I think there is not need to explain what "Inside count" button is.

Suggested change

6. Note the current "Inside count" value, then tap the "Inside count" button (the one

that sits in the region the modal was just covering) several times. Tap "Outside

6. Note the current "Inside count" value, then tap the "Inside count" button several times. Tap "Outside

updated: aa4a870

LKuchno · 2026-06-22T09:12:37Z

+
+10. Tap "Close".
+
+- [ ] Expected: The modal dismisses smoothly and the screen returns to the partial-provider layout. "Inside count" is tappable again and "Outside count" keeps working.


I would add separate step here to check tapping on buttons or add this action to step 10 description.

done: aa4a870

t0maboro · 2026-06-24T17:12:34Z

Some code cleanup is needed here. I wouldn't copy the whole FormSheet implementation unless the specific part is required right now.

done: dc57862

such approach is temporary - implementing a custom shadow node will be handled in a separate pr

- ContainedModal.tsx - ContainedModal.types.ts - ContainedModalProvider.tsx - ContainedModalProvider.types.ts - index.tsx

…inerId for the modal

LKuchno

Few more remarks, mostly suggestion to align with structure after PR#4201

LKuchno · 2026-06-30T13:29:24Z

+
+1. Launch the app and navigate to the **Basic functionality** screen.
+
+- [ ] Expected: Content is shown with the "Provider: full screen (tap for partial)" button, an "Open contained modal" button, an "Outside count: 0" button, and (inside the provider region) an "Inside count: 0" button.


Information about color should be provided also in scenario imo.

LKuchno · 2026-06-30T13:32:18Z

+import type { ScenarioGroup } from '@apps/tests/shared/helpers';
+import TestContainedModalBase from './test-contained-modal-base-ios';
+import TestContainedModalPresentationStyle from './test-contained-modal-presentation-style-ios';
+


After PR #4201 we should also add this exports:

Suggested change

export { default as TestContainedModalBase } from './test-contained-modal-base-ios';

export { default as TestContainedModalPresentationStyle } from './test-contained-modal-presentation-style-ios';

LKuchno · 2026-06-30T13:33:22Z

+
+const CONTAINER_ID = 'contained-modal-transparent';
+
+export function App() {


After PR#4201 we follow this function name convention:

Suggested change

export function App() {

function TestContainedModalPresentationStyle() {

LKuchno · 2026-06-30T13:33:45Z

+  },
+});
+
+export default createScenario(App, scenarioDescription);


After PR mentioned above:

Suggested change

export default createScenario(App, scenarioDescription);

export default createScenario(TestContainedModalPresentationStyle, scenarioDescription);

LKuchno · 2026-06-30T13:34:37Z

+
+const CONTAINER_ID = 'contained-modal-base';
+
+export function App() {


After PR#4201 we should follow this function name convention:

Suggested change

export function App() {

function TestContainedModalBase() {

LKuchno · 2026-06-30T13:34:52Z

+  },
+});
+
+export default createScenario(App, scenarioDescription);


Following above changes:

Suggested change

export default createScenario(App, scenarioDescription);

export default createScenario(TestContainedModalBase, scenarioDescription);

sgaczol force-pushed the @sgaczol/contained-modal branch from f74bf6a to 2d121b6 Compare June 18, 2026 11:42

sgaczol requested review from Copilot, kkafar, kligarski, kmichalikk and t0maboro June 18, 2026 11:53

Copilot started reviewing on behalf of sgaczol June 18, 2026 11:54 View session

sgaczol requested a review from LKuchno June 18, 2026 11:54

sgaczol changed the title ~~feat(iOS, ContainedModal): add a ContainedModal component~~ feat(iOS, ContainedModal): Add basic setup for ContainedModal native component Jun 18, 2026

Copilot AI reviewed Jun 18, 2026

View reviewed changes

LKuchno reviewed Jun 22, 2026

View reviewed changes

t0maboro reviewed Jun 24, 2026

View reviewed changes

sgaczol added 18 commits June 30, 2026 11:15

ContainedModal and ContainedModalProvider codegen setup

06119c1

remove interfaceOnly: true from ContainedModal codegen file

de32542

such approach is temporary - implementing a custom shadow node will be handled in a separate pr

update codegen files

b27481a

added files on js side:

6c64722

- ContainedModal.tsx - ContainedModal.types.ts - ContainedModalProvider.tsx - ContainedModalProvider.types.ts - index.tsx

import fix

1b29727

naming convention

6023f3c

add ContainedModal to experimental

048a38f

import type

a4e6f58

add interfaceOnly: true

716e892

rename codegen files

6a8ab74

codegen name fix

9c71735

package.json fix

6dc3f7d

update

dd933ad

provider name change

f7a346b

stubs added

675af65

providerKey renamed into containerId for the provider and targetConta…

a0c8fd6

…inerId for the modal

comment update

357d00b

add RNSContainedModal on native side

bf1311b

sgaczol added 6 commits June 30, 2026 11:15

added a single feature test

73fafc7

scenario.md update

b9434f0

scenario.md update

9ac275f

transparent prop added for presentation style

97311eb

a single-feature-test for presentation style added

dc7b9ee

cleanup

dc57862

sgaczol force-pushed the @sgaczol/contained-modal branch from 33e1e12 to dc57862 Compare June 30, 2026 09:25

sgaczol added 4 commits June 30, 2026 11:31

stubs update

ff3d9b9

outdated todo removed

fe11e6c

tests updates

aa4a870

update scenario.md

10d835b

LKuchno requested changes Jul 1, 2026

View reviewed changes

t0maboro mentioned this pull request Jul 1, 2026

feat(iOS, ContainedModal): add ContainedModal and ContainedModalProvider related files on JS side #4171

Draft

4 tasks


		1. Launch the app and navigate to the Basic functionality screen.

		- [ ] Expected: Content is shown with the "Provider: full screen (tap for partial)" button, an "Open contained modal" button, an "Outside count: 0" button, and (inside the provider region) an "Inside count: 0" button.

		6. Note the current "Inside count" value, then tap the "Inside count" button (the one
		that sits in the region the modal was just covering) several times. Tap "Outside


		10. Tap "Close".

		- [ ] Expected: The modal dismisses smoothly and the screen returns to the partial-provider layout. "Inside count" is tappable again and "Outside count" keeps working.



	export { default as TestContainedModalBase } from './test-contained-modal-base-ios';
	export { default as TestContainedModalPresentationStyle } from './test-contained-modal-presentation-style-ios';


		const CONTAINER_ID = 'contained-modal-transparent';

		export function App() {

	export function App() {
	function TestContainedModalPresentationStyle() {

	export default createScenario(App, scenarioDescription);
	export default createScenario(TestContainedModalPresentationStyle, scenarioDescription);


		const CONTAINER_ID = 'contained-modal-base';

		export function App() {

Uh oh!

Uh oh!

Conversation

sgaczol commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Things to do

Description

Changes

After - visual documentation

Test plan

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LKuchno left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LKuchno left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sgaczol commented Jun 18, 2026 •

edited

Loading